<html xmlns:saxon="http://icl.com/saxon">
   <head>
      <link rel="stylesheet" type="text/css" href="doc.css"/>
      <link rel="stylesheet" type="text/css" href=""/>
      <meta author="The MathWorks Ltd."/>
      <meta copyright="2011 The MathWorks Ltd."/>
      <title>Dock and undock</title>
   </head>

   
    <body>
      <table class="header" width="100%" border="0" cellspacing="0" cellpadding="0">
         <tr>
            <td bgcolor="#e4f0f8"><A href="User guide.html"><font face="Arial" bgcolor="#e4f0f8" size="+0" underline="0" color="#000000"><b>User guide</b></font></A></td>
            <td width="36" bgcolor="#e4f0f8"><A HREF="User guide5_2.html"><IMG SRC="Images/leftarrow.png" BORDER="0" ALT="previous page"/></A><A HREF="User guide6.html"><IMG SRC="Images/rightarrow.png" BORDER="0" ALT="next page"/></A></td>
         </tr>
      </table>
   

      <br clear="all"/>
          
      <h2>5.3: Dock and undock&nbsp;<a href="User guide5.html"><img src="Images/uparrow.png" border="0" align="top" alt="Go back up one level"/></a></h2>
      
        
        <p>
            When a <a href="uiextras.BoxPanel.html"><code class="FUNCTION">uiextras.BoxPanel</code></a> has its "DockFcn"
            filled in, a dock/undock button (<img src="Images/panelDock.png"/> / <img src="Images/panelUndock.png"/>) is shown in the upper-right of the
            title-bar. When the user clicks this button the specified function
            is called. Since re-docking the panel into its previous parent
            depends on the type of parent, it is up to the user to write
            some code to actually extract or insert the panel.
        </p>
             <p>The following simple example shows how to add dock/undock
                 functionality to a box full of panels. Save the code into
                 a file called "dockexample.m" to run it.</p>
                 
                 <p>(The code for this example can be found here: 
                     [ <a href="Examples/dockexample.m">view</a>
                     | <a href="matlab: edit(fullfile(layoutRoot,'layoutHelp','Examples','dockexample.m'))">edit</a>
                     | <a href="matlab: p=pwd();cd(fullfile(layoutRoot,'layoutHelp','Examples')); dockexample; cd(p)">run</a> ]
                 )</p>
       
            <h4>Create the layout with three panels</h4>
            <p>Open a new figure window and add three panels.</p>
            <example><pre style="background-color: #eeeeff; margin-left: 20px; margin-right: 20px"><font color="#000011"><a href="matlab:doc function"><code class="FUNCTION">function</code></a> dockexample()
<code class="COMMENT">% Create the window and main layout</code>
fig = <a href="matlab:doc figure"><code class="FUNCTION">figure</code></a>( <code class="STRING">'Name'</code>, <code class="STRING">'Dockable GUI example'</code>, ...
              <code class="STRING">'NumberTitle'</code>, <code class="STRING">'off'</code>, ...
              <code class="STRING">'Toolbar'</code>, <code class="STRING">'none'</code>, ...
              <code class="STRING">'MenuBar'</code>, <code class="STRING">'none'</code>, ...
              <code class="STRING">'CloseRequestFcn'</code>, @nCloseAll );
box = <a href="uiextras.HBox.html"><code class="FUNCTION">uiextras.HBox</code></a>( <code class="STRING">'Parent'</code>, fig );

<code class="COMMENT">% Add three panels to the box</code>
panel{1} = <a href="uiextras.BoxPanel.html"><code class="FUNCTION">uiextras.BoxPanel</code></a>( <code class="STRING">'Title'</code>, <code class="STRING">'Panel 1'</code>, <code class="STRING">'Parent'</code>, box );
panel{2} = <a href="uiextras.BoxPanel.html"><code class="FUNCTION">uiextras.BoxPanel</code></a>( <code class="STRING">'Title'</code>, <code class="STRING">'Panel 2'</code>, <code class="STRING">'Parent'</code>, box );
panel{3} = <a href="uiextras.BoxPanel.html"><code class="FUNCTION">uiextras.BoxPanel</code></a>( <code class="STRING">'Title'</code>, <code class="STRING">'Panel 3'</code>, <code class="STRING">'Parent'</code>, box );

<code class="COMMENT">% Add some contents</code><br/>
<a href="matlab:doc uicontrol"><code class="FUNCTION">uicontrol</code></a>( <code class="STRING">'Style'</code>, <code class="STRING">'PushButton'</code>, <code class="STRING">'String'</code>, <code class="STRING">'Button 1'</code>, <code class="STRING">'Parent'</code>, panel{1} );
<a href="matlab:doc uicontrol"><code class="FUNCTION">uicontrol</code></a>( <code class="STRING">'Style'</code>, <code class="STRING">'PushButton'</code>, <code class="STRING">'String'</code>, <code class="STRING">'Button 2'</code>, <code class="STRING">'Parent'</code>, panel{2} );
<a href="matlab:doc uicontrol"><code class="FUNCTION">uicontrol</code></a>( <code class="STRING">'Style'</code>, <code class="STRING">'PushButton'</code>, <code class="STRING">'String'</code>, <code class="STRING">'Button 3'</code>, <code class="STRING">'Parent'</code>, panel{3} );</font></pre>
            <p style="background-color: #ddddee; margin-left: 20px; margin-right: 20px"><font color="#000022"><center><img src="Images/BoxPanelDockExample1.png"/></center></font></p>
        </example>
        
            <h4>Add the dock/undock callback</h4>
            <p>We set each panel to call the same dock/undock function.
        This function is nested inside the main function so that it has access
    to the main function's variables. A better way to do this is to make the
main function into a class, but this nested-function approach is fine
for simple applications.</p>
            <p>Note that as soon as we set the "DockFcn" property the Dock/Undock
                icon appears in the top-right of each panel. We use a cell-array to pass an
            extra argument, the panel number, to the minimize function. This extra argument appears after the usual
            <code>eventSource</code> and <code>eventData</code> arguments.</p>
            <example><pre style="background-color: #eeeeff; margin-left: 20px; margin-right: 20px"><font color="#000011"><code class="COMMENT">% Set the dock/undock callback</code><br/>
<a href="matlab:doc set"><code class="FUNCTION">set</code></a>( panel{1}, <code class="STRING">'DockFcn'</code>, {@nDock, 1} );
<a href="matlab:doc set"><code class="FUNCTION">set</code></a>( panel{2}, <code class="STRING">'DockFcn'</code>, {@nDock, 2} );
<a href="matlab:doc set"><code class="FUNCTION">set</code></a>( panel{3}, <code class="STRING">'DockFcn'</code>, {@nDock, 3} );

<code class="COMMENT">%-------------------------------------------------------------------------%</code><br/> 
    <a href="matlab:doc function"><code class="FUNCTION">function</code></a> nDock( eventSource, eventData, whichpanel )
        <code class="COMMENT">% Set the flag</code>
        panel{whichpanel}.IsDocked = ~panel{whichpanel}.IsDocked;
        <a href="matlab:doc if"><code class="FUNCTION">if</code></a> panel{whichpanel}.IsDocked
            <code class="COMMENT">% Put it back into the layout</code>
            newfig = <a href="matlab:doc get"><code class="FUNCTION">get</code></a>( panel{whichpanel}, <code class="STRING">'Parent'</code> );
            <a href="matlab:doc set"><code class="FUNCTION">set</code></a>( panel{whichpanel}, <code class="STRING">'Parent'</code>, box );
            <a href="matlab:doc delete"><code class="FUNCTION">delete</code></a>( newfig );
        <a href="matlab:doc else"><code class="FUNCTION">else</code></a>&nbsp;
            <code class="COMMENT">% Take it out of the layout</code>
            pos = <a href="matlab:doc getpixelposition"><code class="FUNCTION">getpixelposition</code></a>( panel{whichpanel} );
            newfig = <a href="matlab:doc figure"><code class="FUNCTION">figure</code></a>( ...
                <code class="STRING">'Name'</code>, <a href="matlab:doc get"><code class="FUNCTION">get</code></a>( panel{whichpanel}, <code class="STRING">'Title'</code> ), ...
                <code class="STRING">'NumberTitle'</code>, <code class="STRING">'off'</code>, ...
                <code class="STRING">'MenuBar'</code>, <code class="STRING">'none'</code>, ...
                <code class="STRING">'Toolbar'</code>, <code class="STRING">'none'</code>, ...
                <code class="STRING">'CloseRequestFcn'</code>, {@nDock, whichpanel} );
            figpos = <a href="matlab:doc get"><code class="FUNCTION">get</code></a>( newfig, <code class="STRING">'Position'</code> );
            <a href="matlab:doc set"><code class="FUNCTION">set</code></a>( newfig, <code class="STRING">'Position'</code>, [figpos(1,1:2), pos(1,3:4)] );
            <a href="matlab:doc set"><code class="FUNCTION">set</code></a>( p{whichpanel}, <code class="STRING">'Parent'</code>, newfig, ...
                <code class="STRING">'Units'</code>, <code class="STRING">'Normalized'</code>, ...
                <code class="STRING">'Position'</code>, [0 0 1 1] );
        <a href="matlab:doc end"><code class="FUNCTION">end</code></a>&nbsp;
    <a href="matlab:doc end"><code class="FUNCTION">end</code></a>&nbsp;<code class="COMMENT">% nDock</code></font></pre></example>

        
            <h4>Add the close callback</h4>
            <p>If the user closes the main window we need to also close any
            other windows that were created. This can be done by finding 
            the window that contains each panel and deleting it.</p>
            <example><pre style="background-color: #eeeeff; margin-left: 20px; margin-right: 20px"><font color="#000011"><code class="COMMENT">%-------------------------------------------------------------------------%</code><br/> 
   <a href="matlab:doc function"><code class="FUNCTION">function</code></a> nCloseAll( ~, ~ )
      <a href="matlab:doc for"><code class="FUNCTION">for</code></a> ii=1:<a href="matlab:doc numel"><code class="FUNCTION">numel</code></a>( panel )
         <a href="matlab:doc if"><code class="FUNCTION">if</code></a> <a href="matlab:doc isvalid"><code class="FUNCTION">isvalid</code></a>( panel{ii} ) && ~<a href="matlab:doc strcmpi"><code class="FUNCTION">strcmpi</code></a>( panel{ii}.BeingDeleted, <code class="STRING">'on'</code> )
            figh = <a href="matlab:doc ancestor"><code class="FUNCTION">ancestor</code></a>( panel{ii}, <code class="STRING">'figure'</code> );
            <a href="matlab:doc delete"><code class="FUNCTION">delete</code></a>( figh );
         <a href="matlab:doc end"><code class="FUNCTION">end</code></a>&nbsp;
      <a href="matlab:doc end"><code class="FUNCTION">end</code></a>&nbsp;
        
   <a href="matlab:doc end"><code class="FUNCTION">end</code></a>&nbsp;<code class="COMMENT">% nCloseAll</code>
<a href="matlab:doc end"><code class="FUNCTION">end</code></a>&nbsp;<code class="COMMENT">% Main function</code></font></pre>
            <p style="background-color: #ddddee; margin-left: 20px; margin-right: 20px"><font color="#000022"><center><img src="Images/BoxPanelDockExample2.png"/></center></font></p>
        </example>
        
            <h4>Click the dock buttons</h4>
            <p>Undocking the middle panel causes the other two to fill the
        vacated space. The undocked panel appears in its own window, with the
    "Undock" icon replaced by a "Dock" icon.</p>
            <example><p style="background-color: #ddddee; margin-left: 20px; margin-right: 20px"><font color="#000022"><center><img src="Images/BoxPanelDockExample3.png"/>.<img src="Images/BoxPanelDockExample4.png"/></center></font></p></example>
            <p> Re-docking the panel would
            cause it to be appended to the right of the list in the original window. Closing the main window
        causes all panels, docked or undocked, and their enclosing windows to be closed.</p>

      
      <br clear="ALL"/>
      <table class="footer" width="100%" border="0" cellspacing="0" cellpadding="0">
         <tr>
            <td width="18" height="15" bgcolor="#e4f0f8" align="left"><a href="User guide5_2.html"><img src="images/leftarrow.png" border="0" alt="previous page"/></a></td>
            <td width="40%" height="15" bgcolor="#e4f0f8" align="left"><a href="User guide5_2.html"><font face="arial" bgcolor="#e4f0f8" size="normal" underline="0" color="#000000">Minimize and maximize</font></a></td>
            <td width="20%" height="15" bgcolor="#e4f0f8" align="center"><a href="index.html"><font face="arial" bgcolor="#e4f0f8" size="normal" underline="0" color="#000000">[Top]</font></a></td>
            <td width="40%" height="15" bgcolor="#e4f0f8" align="right"><a href="User guide6.html"><font face="arial" bgcolor="#e4f0f8" size="normal" underline="0" color="#000000">Using layouts inside GUIDE GUIs</font></a></td>
            <td width="18" height="15" bgcolor="#e4f0f8" align="right"><a href="User guide6.html"><img src="images/rightarrow.png" border="0" alt="next page"/></a></td>
         </tr>
      </table>
      <font face="Arial" bgcolor="#e4f0f8" size="normal" underline="0" color="#000000">&copy; 2011 The MathWorks Ltd</font>
      <TT>&#149; </TT><a href="matlab: helpview([matlabroot,'/license.txt'])">Terms of Use</a>
      <TT>&#149; </TT><a href="matlab: helpview([matlabroot,'/patents.txt'])">Patents</a>
      <TT>&#149; </TT><a href="matlab: helpview([matlabroot,'/trademarks.txt'])">Trademarks</a>
   
   </body>
</html>

            
